feat(linux): ship a Flatpak bundle with each release - #767

Greptile Summary

The PR adds amd64 and arm64 Flatpak bundles to the existing Linux packaging and release pipeline.

• Builds the complete OpenLogi product set inside the Freedesktop SDK.
• Stamps AppStream metadata from the checked-out workspace and commit.
• Adds generated bundles to release checksums, signatures, R2 storage, and GitHub Release assets.
• Documents installation and the required host-side udev setup.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  S[Checked-out release tree] --> B[Flatpak matrix build]
  B --> X[amd64 bundle]
  B --> A[arm64 bundle]
  X --> P[Release publisher]
  A --> P
  P --> C[SHA-256 checksums]
  P --> M[Minisign signatures]
  C --> G[GitHub Release and R2]
  M --> G

_{Reviews (5): Last reviewed commit: "docs(linux): document the Flatpak bundle..." | Re-trigger Greptile}

Both review findings are resolved.

Version/ref mismatch (P1). Fixed in 754a2e5. resolve now emits the ref alongside the version and the two move together: a release builds its tag, a dispatch naming a version builds that tag, and a dispatch naming none builds the ref it ran on and labels it with the workspace version. Previously the version was a label only, so a dispatch could have published one tree signed under another tree's release identity.

Action pinning (P2). Settled as a non-issue for this workflow: every action in the publish job is first-party actions/*, on the same mutable tags release.yml and windows-sign-dryrun.yml already use while handling Apple codesign certs and Azure signing credentials. Pinning here alone would make it the only pinned workflow in the tree, and with no Dependabot or Renovate config the SHAs would go stale unnoticed. 12ec9e1 records that reasoning next to the job so it does not have to be rediscovered, and says to follow a repo-wide pinning policy here if one is ever adopted. Happy to pin if you would prefer it, or to do the repo-wide version as a separate PR.

CI status. Green on 12ec9e1, including the macOS test matrix. Locally all three commits also pass cargo xtask ci: 8 passed, 0 failed, 1 skipped, the skip being tests (macos) for want of a Mac.

Thanks for the approval. One thing to flag before v0.7.5 ships: publishing is gated on a FLATPAK_GPG_PRIVATE_KEY repository secret. Without it the workflow still builds both architectures and uploads artifacts, but the publish job skips and no repository is deployed, so the remote that users would add based on the docs wouldn't exist yet.

Whoever sets the key will also need to set GitHub Pages to deploy from GitHub Actions. Happy to write up the key generation steps if that's useful.

FLATPAK_GPG_PRIVATE_KEY

Great call out @AprilNEA would have the update the ENV variable before going live :)

Just to clarify where it goes, it's a repository secret rather than an env variable, under
Settings -> Secrets and variables -> Actions,
since the workflow reads it as secrets.FLATPAK_GPG_PRIVATE_KEY.

I ran the numbers on what a Flatpak userbase would put through this remote, which I should have done before opening the PR, and Pages doesn't hold up as I didn't take into account how many users use this app.

Upstream releases about 17 times a month, and a full pull is roughly 31.5 MiB per arch. At a few thousand people updating, that's somewhere between 200 GB and 1 TB a month against a 100 GB allowance on GitHub Pages. Deltas help but they can't close a 5x gap, since at this release cadence people are often more than one commit behind and the delta stops applying.

I'd also like to have a go at getting this onto Flathub. It needs vendored offline builds. I've scoped that out and it's doable, but realistically a few weeks of verification to get approved.

So for the meantime, two options, rather than me rewriting this PR unasked:

1. Drop the repo from this PR and just ship a bundle: flatpak build-bundle gives you one 21.2 MB file per arch as a release asset. Downside is no auto-updates, but Flathub can replace it in the future. The PR shrinks to a manifest plus one build job. It's still worth having on its own for distros where neither .deb nor .rpm is native, and for the immutable ones where Flatpak is the normal way to install anything.

2. Switch it to Cloudflare R2: I've tested this end to end and signed commits verify fine. R2 doesn't charge for bandwidth or cap it, which is the thing that makes Pages unworkable here. Class B (GET or HEAD request) operations do scale with userbase: free up to about 9,600 clients (10M Class B ops), $0.15/mo at 10k, $3.90 at 20k, around $34 at 100k, worst case with no deltas applying.

   Those numbers are for the bucket on its own. Putting it behind a custom domain with a couple of cache rules changes that, since a cached request doesn't reach the bucket and so isn't billed as an operation. Origin traffic then works out at roughly 90 objects per release times however many datacentres serve them, which lands somewhere well under a million operations a month against a 10 million free tier. That holds at 10k users or 100k.

Whoever owns the bucket ends up owning the signing key and the bill, so that part is your call either way.

Since writing this I've put option 2 up so you can look at it working:
The flatpak repo: https://openlogi.aalman.dev
source: https://github.com/AalmanSadath/openlogi-flatpak

Same manifest as this PR with the publish switched to R2. Signed commits verify, the history goes back to v0.7.2 so deltas have something to apply against (about 3 MB for a one release jump instead of 31 MB), and with the cache rules in front of it everything sits inside the free tier. Each release there also carries the bundles from option 1, so both options are visible in one place.

This is a stopgap running on my own account, not me trying to own the Linux distribution. If you'd rather run it yourselves I'll hand the workflow over as is, and whenever that happens or Flathub lands, I'll archive mine and point people at yours.

Please make it so it goes on Flathub. It will show up in everyone's app stores.

Dropping the repo and starting with flatpak build-bundle would be a good first step. It adds a portable build (at least similar to what an AppImage would do) and would allow kicking off Flathub inclusion. Flathub is the de-facto place for Flatpaks; I think that a private repo is honestly a lot less attractive and a lot more to maintain.

Want your agent to iterate on Greptile's feedback? Start a greploop in Codex and it will work through the open comments and keep going until this PR reviews clean.

I've reworked this to drop the repository half. It now only builds the .flatpak
bundles and attaches them to the release, which is roughly half the size and
adds no new workflow.

The reason is the numbers I posted above: Pages does not carry the traffic a
Flatpak userbase would put through a remote, and the alternative is a bucket
plus a signing key. Both are yours to own and pay for, and I would rather not
make merging this conditional on that decision. A repository can still be added
later and nothing here works against it.

So the earlier FLATPAK_GPG_PRIVATE_KEY note no longer applies as there is
nothing to sign a repository with, and no secret to set. Sorry for the churn on
that, @davidbudnick.

What it does not do: bundles have no remote behind them, so flatpak update
has nothing to check and this does not close #605. It does give atomic
distributions an install path (#681).

Both arch legs build green in CI and the amd64 bundle installs and runs. One
thing worth knowing before judging the checks: should-build skips the whole
matrix for a PR without the needs: build label, so the green tick here has not
actually run the new job.

Also fixed a Greptile P1 from the closed duplicate: the minisign loop covers
every other shipped artifact, and the bundle was missing from it. It would have
been the one installer a user could not verify, in both the release and the R2
copy.